OPTIONS
OPTIONS Global Options These options can be specified on the command line at any point before the first effect name. The SOX_OPTS environment variable can be used to provide alternative default values for SoX’s global options. For example: SOX_OPTS="−−buffer 20000 −−play−rate−arg −hs −−temp /mnt/temp" Note that setting SOX_OPTS can potentially create unwanted changes in the behaviour of scripts or other programs that invoke SoX. SOX_OPTS might best be used for things (such as in the given example) that reflect the environment in which SoX is being run. Enabling options such as −−no−clobber as default might be handled better using a shell alias since a shell alias will not affect operation in scripts etc. One way to ensure that a script cannot be affected by SOX_OPTS is to clear SOX_OPTS at the start of the script, but this of course loses the benefit of SOX_OPTS carrying some system-wide default options. An alternative approach is to explicitly invoke SoX with default option values, e.g. SOX_OPTS="−V −−no-clobber" ... sox −V2 −−clobber $input $output ... Note that the way to set environment variables varies from system to system. Here are some examples: Unix bash: export SOX_OPTS="−V −−no-clobber" Unix csh: setenv SOX_OPTS "−V −−no-clobber" MS-DOS/MS-Windows: set SOX_OPTS=−V −−no-clobber MS-Windows GUI: via Control Panel : System : Advanced : Environment Variables Mac OS X GUI: Refer to Apple’s Technical Q&A QA1067 document. ' −−buffer BYTES', −−input−buffer BYTES Set the size in bytes of the buffers used for processing audio (default 8192). −−buffer applies to input, effects, and output processing; −−input−buffer applies only to input processing (for which it overrides −−buffer if both are given). Be aware that large values for −−buffer will cause SoX to be become slow to respond to requests to terminate or to skip the current input file. −−clobber Don’t prompt before overwriting an existing file with the same name as that given for the output file. This is the default behaviour. −−combine concatenate|'merge'|'mix'|'mix−power'|'multiply'|'sequence' Select the input file combining method; for some of these, short options are available: −m selects ‘mix’, −M selects ‘merge’, and −T selects ‘multiply’. See Input File Combining above for a description of the different combining methods. −D, −−no−dither Disable automatic dither - see ‘Dithering’ above. An example of why this might occasionally be useful is if a file has been converted from 16 to 24 bit with the intention of doing some processing on it, but in fact no processing is needed after all and the original 16 bit file has been lost, then, strictly speaking, no dither is needed if converting the file back to 16 bit. See also the stats effect for how to determine the actual bit depth of the audio within a file. −−effects−file FILENAME Use FILENAME to obtain all effects and their arguments. The file is parsed as if the values were specified on the command line. A new line can be used in place of the special :' marker to separate effect chains. For convenience, such markers at the end of the file are normally ignored; if you want to specify an empty last effects chain, use an explicit ': by itself on the last line of the file. This option causes any effects specified on the command line to be discarded. −G, −−guard Automatically invoke the gain effect to guard against clipping. E.g. sox −G infile −b 16 outfile rate 44100 dither −s is shorthand for sox infile −b 16 outfile gain −h rate 44100 gain −rh dither −s See also −V, −−norm, and the gain effect. −h, −−help Show version number and usage information. −−help−effect NAME Show usage information on the specified effect. The name all can be used to show usage on all effects. −−help−format NAME Show information about the specified file format. The name all can be used to show information on all formats. −−i, −−info Only if given as the first parameter to sox, behave as soxi(1). −−magic If SoX has been built with the optional ‘libmagic’ library then this option can be given to enable its use in helping to detect audio file types. −−multi−threaded | −−single−threaded By default, SoX is ‘single threaded’. If the −−multi−threaded option is given however then SoX will process audio channels for most multi-channel effects in parallel on hyper-threading/multi-core architectures. This may reduce processing time, though sometimes it may be necessary to use this option in conjuction with a larger buffer size than is the default to gain any benefit from multi-threaded processing (e.g. 131072; see −−buffer above). −−no−clobber Prompt before overwriting an existing file with the same name as that given for the output file. N.B. Unintentionally overwriting a file is easier than you might think, for example, if you accidentally enter sox file1 file2 effect1 effect2 ... when what you really meant was play file1 file2 effect1 effect2 ... then, without this option, file2 will be overwritten. Hence, using this option is recommended. SOX_OPTS (above), a ‘shell’ alias, script, or batch file may be an appropriate way of permanently enabling it. −−norm[=''dB-level''] Automatically invoke the gain effect to guard against clipping and to normalise the audio. E.g. sox −−norm infile −b 16 outfile rate 44100 dither −s is shorthand for sox infile −b 16 outfile gain −h rate 44100 gain −nh dither −s Optionally, the audio can be normalized to a given level (usually) below 0 dBFS: sox −−norm=−3 infile outfile See also −V, −G, and the gain effect. −−play−rate−arg ARG Selects a quality option to be used when the ‘rate’ effect is automatically invoked whilst playing audio. This option is typically set via the SOX_OPTS environment variable (see above). −−plot gnuplot|'octave'|'off' If not set to off (the default if −−plot is not given), run in a mode that can be used, in conjunction with the gnuplot program or the GNU Octave program, to assist with the selection and configuration of many of the transfer-function based effects. For the first given effect that supports the selected plotting program, SoX will output commands to plot the effect’s transfer function, and then exit without actually processing any audio. E.g. sox −−plot octave input-file −n highpass 1320 > highpass.plt octave highpass.plt −q, −−no−show−progress Run in quiet mode when SoX wouldn’t otherwise do so. This is the opposite of the −S option. −−replay−gain track|'album'|'off' Select whether or not to apply replay-gain adjustment to input files. The default is off for sox and rec, album for play where (at least) the first two input files are tagged with the same Artist and Album names, and track for play otherwise. −S, −−show−progress Display input file format/header information, and processing progress as input file(s) percentage complete, elapsed time, and remaining time (if known; shown in brackets), and the number of samples written to the output file. Also shown is a peak-level meter, and an indication if clipping has occurred. The peak-level meter shows up to two channels and is calibrated for digital audio as follows (right channel shown): A three-second peak-held value of headroom in dBs will be shown to the right of the meter if this is below 6dB. This option is enabled by default when using SoX to play or record audio. −−temp DIRECTORY Specify that any temporary files should be created in the given DIRECTORY. This can be useful if there are permission or free-space problems with the default location. In this case, using ‘'−−temp .'’ (to use the current directory) is often a good solution. −−version Show SoX’s version number and exit. −V[level] Set verbosity. This is particularly useful for seeing how any automatic effects have been invoked by SoX. SoX displays messages on the console (stderr) according to the following verbosity levels: 4 and above Messages to help with debugging SoX are also shown. By default, the verbosity level is set to 2 (shows errors and warnings). Each occurrence of the −V option increases the verbosity level by 1. Alternatively, the verbosity level can be set to an absolute number by specifying it immediately after the −V, e.g. −V0 sets it to 0. Input File Options These options apply only to input files and may precede only input filenames on the command line. ' −−ignore−length' Override an (incorrect) audio length given in an audio file’s header. If this option is given then SoX will keep reading audio until it reaches the end of the input file. −v, −−volume FACTOR Intended for use when combining multiple input files, this option adjusts the volume of the file that follows it on the command line by a factor of FACTOR. This allows it to be ‘balanced’ w.r.t. the other input files. This is a linear (amplitude) adjustment, so a number less than 1 decreases the volume and a number greater than 1 increases it. If a negative number is given then in addition to the volume adjustment, the audio signal will be inverted. See also the norm, vol, and gain effects, and see Input File Balancing above. Input & Output File Format Options These options apply to the input or output file whose name they immediately precede on the command line and are used mainly when working with headerless file formats or when specifying a format for the output file that is different to that of the input file. ' −b' BITS, −−bits BITS The number of bits (a.k.a. bit-depth or sometimes word-length) in each encoded sample. Not applicable to complex encodings such as MP3 or GSM. Not necessary with encodings that have a fixed number of bits, e.g. A/μ-law, ADPCM. For an input file, the most common use for this option is to inform SoX of the number of bits per sample in a ‘raw’ (‘headerless’) audio file. For example sox −r 16k −e signed −b 8 input.raw output.wav converts a particular ‘raw’ file to a self-describing ‘WAV’ file. For an output file, this option can be used (perhaps along with −e) to set the output encoding size. By default (i.e. if this option is not given), the output encoding size will (providing it is supported by the output file type) be set to the input encoding size. For example sox input.cdda −b 24 output.wav converts raw CD digital audio (16-bit, signed-integer) to a 24-bit (signed-integer) ‘WAV’ file. −1/'−2'/'−3'/'−4'/'−8' The number of bytes in each encoded sample. Deprecated aliases for −b 8, −b 16, −b 24, −b 32, −b 64 respectively. −c CHANNELS, −−channels CHANNELS The number of audio channels in the audio file. This can be any number greater than zero. For an input file, the most common use for this option is to inform SoX of the number of channels in a ‘raw’ (‘headerless’) audio file. Occasionally, it may be useful to use this option with a ‘headered’ file, in order to override the (presumably incorrect) value in the header - note that this is only supported with certain file types. Examples: sox −r 48k −e float −b 32 −c 2 input.raw output.wav converts a particular ‘raw’ file to a self-describing ‘WAV’ file. play −c 1 music.wav interprets the file data as belonging to a single channel regardless of what is indicated in the file header. Note that if the file does in fact have two channels, this will result in the file playing at half speed. For an output file, this option provides a shorthand for specifying that the channels effect should be invoked in order to change (if necessary) the number of channels in the audio signal to the number given. For example, the following two commands are equivalent: sox input.wav −c 1 output.wav bass −b 24 sox input.wav output.wav bass −b 24 channels 1 though the second form is more flexible as it allows the effects to be ordered arbitrarily. −e ENCODING, −−encoding ENCODING The audio encoding type. Sometimes needed with file-types that support more than one encoding type. For example, with raw, WAV, or AU (but not, for example, with MP3 or FLAC). The available encoding types are as follows: ' signed-integer' PCM data stored as signed (‘two’s complement’) integers. Commonly used with a 16 or 24 −bit encoding size. A value of 0 represents minimum signal power. unsigned-integer PCM data stored as unsigned integers. Commonly used with an 8-bit encoding size. A value of 0 represents maximum signal power. floating-point PCM data stored as IEEE 753 single precision (32-bit) or double precision (64-bit) floating-point (‘real’) numbers. A value of 0 represents minimum signal power. u-law, mu-law North American telephony standard for logarithmic encoding to 8 bits per sample. A.k.a. μ-law. It has a precision equivalent to roughly 14-bit PCM and is sometimes encoded with reversed bit-ordering (see the −X option). oki-adpcm OKI (a.k.a. VOX, Dialogic, or Intel) 4-bit ADPCM; it has a precision equivalent to roughly 12-bit PCM. ADPCM is a form of audio compression that has a good compromise between audio quality and encoding/decoding speed. ima-adpcm IMA (a.k.a. DVI) 4-bit ADPCM; it has a precision equivalent to roughly 13-bit PCM. ms-adpcm Microsoft 4-bit ADPCM; it has a precision equivalent to roughly 14-bit PCM. gsm-full-rate GSM is currently used for the vast majority of the world’s digital wireless telephone calls. It utilises several audio formats with different bit-rates and associated speech quality. SoX has support for GSM’s original 13kbps ‘Full Rate’ audio format. It is usually CPU-intensive to work with GSM audio. For an input file, the most common use for this option is to inform SoX of the encoding of a ‘raw’ (‘headerless’) audio file (see the examples in −b and −c above). For an output file, this option can be used (perhaps along with −b) to set the output encoding type For example sox input.cdda −e float output1.wav sox input.cdda −b 64 −e float output2.wav convert raw CD digital audio (16-bit, signed-integer) to floating-point ‘WAV’ files (single & double precision respectively). By default (i.e. if this option is not given), the output encoding type will (providing it is supported by the output file type) be set to the input encoding type. −s/'−u'/'−f'/'−A'/'−U'/'−o'/'−i'/'−a'/'−g' Deprecated aliases for specifying the encoding types signed-integer, unsigned-integer, floating-point, a-law, mu-law, oki-adpcm, ima-adpcm, ms-adpcm, gsm-full-rate respectively (see −e above). −−no−glob Specifies that filename ‘globbing’ (wild-card matching) should not be performed by SoX on the following filename. For example, if the current directory contains the two files ‘five-seconds.wav’ and ‘five*.wav’, then play −−no−glob "five*.wav" can be used to play just the single file ‘five*.wav’. −r, −−rate RATE[k'] Gives the sample rate in Hz (or kHz if appended with ‘k’) of the file. For an input file, the most common use for this option is to inform SoX of the sample rate of a ‘raw’ (‘headerless’) audio file (see the examples in '−b and −c above). Occasionally it may be useful to use this option with a ‘headered’ file, in order to override the (presumably incorrect) value in the header - note that this is only supported with certain file types. For example, if audio was recorded with a sample-rate of say 48k from a source that played back a little, say 1.5%, too slowly, then sox −r 48720 input.wav output.wav effectively corrects the speed by changing only the file header (but see also the speed effect for the more usual solution to this problem). For an output file, this option provides a shorthand for specifying that the rate effect should be invoked in order to change (if necessary) the sample rate of the audio signal to the given value. For example, the following two commands are equivalent: sox input.wav −r 48k output.wav bass −b 24 sox input.wav output.wav bass −b 24 rate 48k though the second form is more flexible as it allows rate options to be given, and allows the effects to be ordered arbitrarily. −t, −−type FILE-TYPE Gives the type of the audio file. For both input and output files, this option is commonly used to inform SoX of the type a ‘headerless’ audio file (e.g. raw, mp3) where the actual/desired type cannot be determined from a given filename extension. For example: another-command | sox −t mp3 − output.wav sox input.wav −t raw output.bin It can also be used to override the type implied by an input filename extension, but if overriding with a type that has a header, SoX will exit with an appropriate error message if such a header is not actually present. See soxformat(7) for a list of supported file types. −L, −−endian little −B, −−endian big −x, −−endian swap N.B. Unlike other format characteristics, the endianness (byte, nibble, & bit ordering) of the input file is not automatically used for the output file; so, for example, when the following is run on a little-endian system: sox −B audio.s16 trimmed.s16 trim 2 trimmed.s16 will be created as little-endian; sox −B audio.s16 −B trimmed.s16 trim 2 must be used to preserve big-endianness in the output file. The −V option can be used to check the selected orderings. −N, −−reverse−nibbles Specifies that the nibble ordering (i.e. the 2 halves of a byte) of the samples should be reversed; sometimes useful with ADPCM-based formats. N.B. See also N.B. in section on −x above. −X, −−reverse−bits Specifies that the bit ordering of the samples should be reversed; sometimes useful with a few (mostly headerless) formats. N.B. See also N.B. in section on −x above. Output File Format Options These options apply only to the output file and may precede only the output filename on the command line. ' −−add−comment' TEXT Append a comment in the output file header (where applicable). −−comment TEXT Specify the comment text to store in the output file header (where applicable). SoX will provide a default comment if this option (or −−comment−file) is not given. To specify that no comment should be stored in the output file, use −−comment "" . −−comment−file FILENAME Specify a file containing the comment text to store in the output file header (where applicable). −C, −−compression FACTOR The compression factor for variably compressing output file formats. If this option is not given then a default compression factor will apply. The compression factor is interpreted differently for different compressing file formats. See the description of the file formats that use this option in soxformat(7) for more information.